<!DOCTYPE html>
<html lang="en">
  <head>
    <title>SideEffect Protocol Reference</title>
    <link rel="stylesheet" type="text/css" href="../css/jazzy.css" />
    <link rel="stylesheet" type="text/css" href="../css/highlight.css" />
    <meta charset="utf-8">
    <script src="../js/jquery.min.js" defer></script>
    <script src="../js/jazzy.js" defer></script>
    
    <script src="../js/lunr.min.js" defer></script>
    <script src="../js/typeahead.jquery.js" defer></script>
    <script src="../js/jazzy.search.js" defer></script>
  </head>
  <body>

    <a name="//apple_ref/swift/Protocol/SideEffect" class="dashAnchor"></a>

    <a title="SideEffect Protocol Reference"></a>

    <header class="header">
      <p class="header-col header-col--primary">
        <a class="header-link" href="../index.html">
          Katana 5.1.1 Docs
        </a>
         (99% documented)
      </p>
    
      <p class="header-col--secondary">
        <form role="search" action="../search.json">
          <input type="text" placeholder="Search documentation" data-typeahead>
        </form>
      </p>
    
        <p class="header-col header-col--secondary">
          <a class="header-link" href="https://github.com/BendingSpoons/katana-swift">
            <img class="header-icon" src="../img/gh.png"/>
            View on GitHub
          </a>
        </p>
    
    </header>

    <p class="breadcrumbs">
      <a class="breadcrumb" href="../index.html">Katana Reference</a>
      <img class="carat" src="../img/carat.png" />
      SideEffect Protocol Reference
    </p>

    <div class="content-wrapper">
      <nav class="navigation">
        <ul class="nav-groups">
          <li class="nav-group-name">
            <a class="nav-group-name-link" href="../Classes.html">Classes</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="../Classes/EmptySideEffectDependencyContainer.html">EmptySideEffectDependencyContainer</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="../Classes/PartialStore.html">PartialStore</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="../Classes/Store.html">Store</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="../Classes/Store/Configuration.html">– Configuration</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a class="nav-group-name-link" href="../Enums.html">Enumerations</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="../Enums/DispatchableLogger.html">DispatchableLogger</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a class="nav-group-name-link" href="../Extensions.html">Extensions</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="../Extensions/DispatchQueue.html">DispatchQueue</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a class="nav-group-name-link" href="../Protocols.html">Protocols</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="../Protocols/AnySideEffect.html">AnySideEffect</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="../Protocols/AnySideEffectContext.html">AnySideEffectContext</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="../Protocols/AnyStateUpdater.html">AnyStateUpdater</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="../Protocols/AnyStore.html">AnyStore</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="../Protocols/AsyncProvider.html">AsyncProvider</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="../Protocols/DispatchObserverDispatchable.html">DispatchObserverDispatchable</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="../Protocols/Dispatchable.html">Dispatchable</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="../Protocols/NotificationObserverDispatchable.html">NotificationObserverDispatchable</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="../Protocols/OnStartObserverDispatchable.html">OnStartObserverDispatchable</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="../Protocols/ReturningSideEffect.html">ReturningSideEffect</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="../Protocols/SideEffect.html">SideEffect</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="../Protocols/SideEffectDependencyContainer.html">SideEffectDependencyContainer</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="../Protocols/State.html">State</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="../Protocols/StateObserverDispatchable.html">StateObserverDispatchable</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="../Protocols/StateUpdater.html">StateUpdater</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a class="nav-group-name-link" href="../Structs.html">Structures</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="../Structs/ObserverInterceptor.html">ObserverInterceptor</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="../Structs/ObserverInterceptor/ObserverType.html">– ObserverType</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="../Structs/SideEffectContext.html">SideEffectContext</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="../Structs/SignpostLogger.html">SignpostLogger</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a class="nav-group-name-link" href="../Typealiases.html">Type Aliases</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="../Typealiases.html#/s:6Katana11AnyDispatcha">AnyDispatch</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="../Typealiases.html#/s:6Katana16AnyStoreListenera">AnyStoreListener</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="../Typealiases.html#/s:6Katana8GetStatea">GetState</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="../Typealiases.html#/s:6Katana16StoreInterceptora">StoreInterceptor</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="../Typealiases.html#/s:6Katana20StoreInterceptorNexta">StoreInterceptorNext</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="../Typealiases.html#/s:6Katana13StoreListenera">StoreListener</a>
              </li>
              <li class="nav-group-task">
                <a class="nav-group-task-link" href="../Typealiases.html#/s:6Katana16StoreUnsubscribea">StoreUnsubscribe</a>
              </li>
            </ul>
          </li>
        </ul>
      </nav>
      <article class="main-content">

        <section class="section">
          <div class="section-content top-matter">
            <h1>SideEffect</h1>
              <div class="declaration">
                <div class="language">
                  
                  <pre class="highlight swift"><code><span class="kd">public</span> <span class="kd">protocol</span> <span class="kt">SideEffect</span> <span class="p">:</span> <span class="kt"><a href="../Protocols/AnySideEffect.html">AnySideEffect</a></span></code></pre>

                </div>
              </div>
            <p>A side effect is a single atom of the logic of your application.
While you can actually use them as you desire, the idea is to implement in each side effect
a meaningful, self contained, piece of logic that can be used from other pieces of you application
(e.g., dispatched by a View Controller or by another side effect).</p>

<p>The <code>SideEffect</code> is strongly tied to the state that it handles and the dependencies it has.
This greatly simplifies the code written in normal situations.
However, if you need to create updaters that are not strictly tied to a concrete types (e.g., in a library)
you can use <code><a href="../Protocols/AnySideEffect.html">AnySideEffect</a></code>.</p>
<h3 id='app-tips-amp-tricks' class='heading'>App Tips &amp; Tricks</h3>

<p>To further simplify the usage of a <code>SideEffect</code> you can add to your application a helper protocol</p>
<pre class="highlight swift"><code><span class="c1">/// assuming `AppState` is the type of your application's state and `DependenciesContainer` is the</span>
<span class="c1">/// container of your dependencies</span>
<span class="kd">protocol</span> <span class="kt">AppSideEffect</span><span class="p">:</span> <span class="kt">SideEffect</span> <span class="k">where</span> <span class="kt">StateType</span> <span class="o">==</span> <span class="kt">AppState</span><span class="p">,</span> <span class="kt">Dependencies</span> <span class="o">==</span> <span class="kt">DependenciesContainer</span> <span class="p">{}</span>
</code></pre>

<p>By conforming to <code>AppSideEffect</code>, you will get better autocompletion</p>

              <div class="slightly-smaller">
                <a href="https://github.com/BendingSpoons/katana-swift/blob/master//Sources/SideEffect.swift#L241-L281">Show on GitHub</a>
              </div>
          </div>
        </section>

        <section class="section">
          <div class="section-content">
            <div class="task-group">
              <ul class="item-container">
                <li class="item">
                  <div>
                    <code>
                    <a name="/s:6Katana10SideEffectP9StateTypeQa"></a>
                    <a name="//apple_ref/swift/Alias/StateType" class="dashAnchor"></a>
                    <a class="token" href="#/s:6Katana10SideEffectP9StateTypeQa">StateType</a>
                    </code>
                  </div>
                  <div class="height-container">
                    <div class="pointer-container"></div>
                    <section class="section">
                      <div class="pointer"></div>
                      <div class="abstract">
                        <p>The type of the state of the store</p>

                      </div>
                      <div class="declaration">
                        <h4>Declaration</h4>
                        <div class="language">
                          <p class="aside-title">Swift</p>
                          <pre class="highlight swift"><code><span class="kd">associatedtype</span> <span class="kt">StateType</span> <span class="p">:</span> <span class="kt"><a href="../Protocols/State.html">State</a></span></code></pre>

                        </div>
                      </div>
                      <div class="slightly-smaller">
                        <a href="https://github.com/BendingSpoons/katana-swift/blob/master//Sources/SideEffect.swift#L243">Show on GitHub</a>
                      </div>
                    </section>
                  </div>
                </li>
                <li class="item">
                  <div>
                    <code>
                    <a name="/s:6Katana10SideEffectP12DependenciesQa"></a>
                    <a name="//apple_ref/swift/Alias/Dependencies" class="dashAnchor"></a>
                    <a class="token" href="#/s:6Katana10SideEffectP12DependenciesQa">Dependencies</a>
                    </code>
                  </div>
                  <div class="height-container">
                    <div class="pointer-container"></div>
                    <section class="section">
                      <div class="pointer"></div>
                      <div class="abstract">
                        <p>The type of the dependencies container that is used to pass dependencies to the side effect</p>

                      </div>
                      <div class="declaration">
                        <h4>Declaration</h4>
                        <div class="language">
                          <p class="aside-title">Swift</p>
                          <pre class="highlight swift"><code><span class="kd">associatedtype</span> <span class="kt">Dependencies</span> <span class="p">:</span> <span class="kt"><a href="../Protocols/SideEffectDependencyContainer.html">SideEffectDependencyContainer</a></span></code></pre>

                        </div>
                      </div>
                      <div class="slightly-smaller">
                        <a href="https://github.com/BendingSpoons/katana-swift/blob/master//Sources/SideEffect.swift#L246">Show on GitHub</a>
                      </div>
                    </section>
                  </div>
                </li>
                <li class="item">
                  <div>
                    <code>
                    <a name="/s:6Katana10SideEffectP04sideC0yyAA0bC7ContextVy9StateTypeQz12DependenciesQzGKF"></a>
                    <a name="//apple_ref/swift/Method/sideEffect(_:)" class="dashAnchor"></a>
                    <a class="token" href="#/s:6Katana10SideEffectP04sideC0yyAA0bC7ContextVy9StateTypeQz12DependenciesQzGKF">sideEffect(_:<wbr>)</a>
                    </code>
                  </div>
                  <div class="height-container">
                    <div class="pointer-container"></div>
                    <section class="section">
                      <div class="pointer"></div>
                      <div class="abstract">
                        <p>Block that implements the logic of the side effect.
You can implement the logic, leveraging the technology you desire for threading and flow management.</p>

<p>However, there are two patterns that Katana suggests to use: synchronous side effects and asynchronous side effects</p>
<h4 id='synchronous' class='heading'>Synchronous</h4>

<p>A synchronous side effect is a side effect that finishes its execution when the <code>sideEffect(:)</code> method
is completed. Since the related promise (that is, the promise that is returned when the side effect is dispatched)
is resolved when this method ends, it means that the caller can safely assume that the operations are completed.</p>

<p>The easier way to achieve this behaviour is by using <code>Hydra.await</code> offered by the <code>Hydra</code> library. You can use <code>Hydra.await</code>
with any API that returns a promise (e.g., the dispatch) and it blocks the execution of the method until the
promise is resolved (you can find more documentation here <a href="https://github.com/malcommac/Hydra/#awaitasync">https://github.com/malcommac/Hydra/#awaitasync</a>).</p>

<p>This should be the default approach you take for your side effects</p>
<h4 id='asynchronous' class='heading'>Asynchronous</h4>

<p>An asynchronous side effect is a side effect that continues to propagate its effect even after the <code>sideEffect(:)</code> method
has been completed. This can be very helpful for very long running operations where you don&rsquo;t want to block
other side effects in the queue.</p>

<p>In order to do use this approach, you can simply apply any asynchronous technique you know that does not block the method
(e.g.: promise, callback).</p>

<p>This approach is not suggested and should be used only in rare cases</p>
<div class="aside aside-throws">
    <p class="aside-title">Throws</p>
    if the logic has an error. The related promise will be rejected

</div><div class="aside aside-see-also">
    <p class="aside-title">See also</p>
    <a href="https://github.com/malcommac/Hydra/#awaitasync">https://github.com/malcommac/Hydra/#awaitasync</a>

</div>

                      </div>
                      <div class="declaration">
                        <h4>Declaration</h4>
                        <div class="language">
                          <p class="aside-title">Swift</p>
                          <pre class="highlight swift"><code><span class="kd">func</span> <span class="nf">sideEffect</span><span class="p">(</span><span class="n">_</span> <span class="nv">context</span><span class="p">:</span> <span class="kt"><a href="../Structs/SideEffectContext.html">SideEffectContext</a></span><span class="o">&lt;</span><span class="kt"><a href="../Protocols/SideEffect.html#/s:6Katana10SideEffectP9StateTypeQa">StateType</a></span><span class="p">,</span> <span class="kt"><a href="../Protocols/SideEffect.html#/s:6Katana10SideEffectP12DependenciesQa">Dependencies</a></span><span class="o">&gt;</span><span class="p">)</span> <span class="k">throws</span></code></pre>

                        </div>
                      </div>
                      <div>
                        <h4>Parameters</h4>
                        <table class="graybox">
                          <tbody>
                            <tr>
                              <td>
                                <code>
                                <em>context</em>
                                </code>
                              </td>
                              <td>
                                <div>
                                  <p>the context of the side effect</p>
                                </div>
                              </td>
                            </tr>
                          </tbody>
                        </table>
                      </div>
                      <div>
                        <h4>Return Value</h4>
                        <p>the side effect return value that will be used to parameterize the related promise</p>
                      </div>
                      <div class="slightly-smaller">
                        <a href="https://github.com/BendingSpoons/katana-swift/blob/master//Sources/SideEffect.swift#L280">Show on GitHub</a>
                      </div>
                    </section>
                  </div>
                </li>
                <li class="item">
                  <div>
                    <code>
                    <a name="/s:6Katana10SideEffectPAAE03anybC0yypAA03AnybC7Context_pKF"></a>
                    <a name="//apple_ref/swift/Method/anySideEffect(_:)" class="dashAnchor"></a>
                    <a class="token" href="#/s:6Katana10SideEffectPAAE03anybC0yypAA03AnybC7Context_pKF">anySideEffect(_:<wbr>)</a>
                    </code>
                      <span class="declaration-note">
                        Extension method
                      </span>
                  </div>
                  <div class="height-container">
                    <div class="pointer-container"></div>
                    <section class="section">
                      <div class="pointer"></div>
                      <div class="abstract">
                        <p>Conformance of <code>SideEffect</code> to <code><a href="../Protocols/ReturningSideEffect.html">ReturningSideEffect</a></code></p>

                      </div>
                      <div class="declaration">
                        <h4>Declaration</h4>
                        <div class="language">
                          <p class="aside-title">Swift</p>
                          <pre class="highlight swift"><code><span class="kd">public</span> <span class="kd">func</span> <span class="nf">anySideEffect</span><span class="p">(</span><span class="n">_</span> <span class="nv">context</span><span class="p">:</span> <span class="kt"><a href="../Protocols/AnySideEffectContext.html">AnySideEffectContext</a></span><span class="p">)</span> <span class="k">throws</span> <span class="o">-&gt;</span> <span class="kt">Any</span></code></pre>

                        </div>
                      </div>
                      <div class="slightly-smaller">
                        <a href="https://github.com/BendingSpoons/katana-swift/blob/master//Sources/SideEffect.swift#L285-L292">Show on GitHub</a>
                      </div>
                    </section>
                  </div>
                </li>
              </ul>
            </div>
          </div>
        </section>

      </article>
    </div>
    <section class="footer">
      <p>&copy; 2021 <a class="link" href="http://bendingspoons.com" target="_blank" rel="external">Bending Spoons Team</a>. All rights reserved. (Last updated: 2021-04-29)</p>
      <p>Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="external">jazzy ♪♫ v0.13.6</a>, a <a class="link" href="https://realm.io" target="_blank" rel="external">Realm</a> project.</p>
    </section>
  </body>
</div>
</html>
